<!doctype html>
<html>
<head>
<meta encoding="utf-8">
<title>Py HTML Contextual Autoescaping</title>
<script src="https://google-code-prettify.googlecode.com/svn/loader/run_prettify.js"></script>
</head>
<body>
<h1>A contextual autoescaper for HTML</h1>

<h2>Runtime auto-escaping</h2>
<p>If analysis can't be done when a template is compiled, 
this module provides a file-like object that provides two methods:</p>

<pre class="prettyprint">
  write_safe(**strings)  # Called with strings that appear in template
  write(**values)        # Called with values supplied by caller at runtime
</pre>

<p>so that the sequence of calls generated by a template</p>

<pre class="prettyprint">
&lt;b&gt;<i>{{ x }}</i>&lt;/b&gt;
&lt;button onclick=foo(<i>{{ y }}</i>)&gt;
</pre>

produce

<pre class="prettyprint">
 w.write_safe('&lt;b&gt;')
 w.write('I &lt;3 Ponies!')
 w.write_safe('&lt;/b&gt;\n&lt;button onclick=foo(')
 w.write({'foo': 'bar', '"baz"': 42})
 w.write_safe(')&gt;')
</pre>

<p>results in the output</p>

<pre class="prettyprint">
  &lt;b&gt;I &amp;lt;3 Ponies!&lt;/b&gt;
  &lt;button onclick="foo({&amp;#34;foo&amp;#34;:&amp;#34;\x22bar\x22&amp;#34;:42})"&gt;
</pre>

<p>
The safe parts are treated as literal chunks of HTML/CSS/JS, and the unsafe
parts are escaped to preserve security and least-surprise.

For a more comprehensive example, a template like
</p>

<pre class="prettyprint">
&lt;div style="color: {{user.color}}"&gt;
  &lt;a href="/{{user.color}}?q={{$user.world}}"
   onclick="alert('{{helper(user)}}');return false"&gt;
    {{helper(user)}}
  &lt;/a&gt;
  &lt;script&gt;(function () {  // Sleepy developers put sensitive info in comments.
    var o = {{user}},
        w = "{{user.world}}";
  })();&lt;/script&gt;
&lt;/div&gt;

{{template helper}}
  Hello, {{user.world}}
{{/template}}
</pre>

<p>might correspond to the sequence of calls</p>

<pre class="prettyprint">
 # Dummy input values.
 user = {
   "world": "&lt;Cincinatti&gt;",
   "color": "blue"
 }
 color = user["color"]
 world = user["world"]
 # Alternating safe and unsafe writes that implement the template.
 w.write_safe("&lt;div style=\"color: ")
 w.write     (color)
 w.write_safe("\"&gt;\n&lt;a href=\"/")
 w.write     (color)
 w.write_safe("?q=")
 w.write     (world)
 w.write_safe("\"\n  onclick=\"alert('")
 helper      (w, user)
 w.write_safe("');return false\"&gt;\n    ")
 helper      (w, user)  # Helper called in a different context
 w.write_safe("\n  &lt;/a&gt;\n  &lt;script&gt;(function () {\n    var o = ")
 w.write     (user)
 w.write_safe(",\n        w = \"")
 w.write     (world)
 w.write_safe("\";\n  })();&lt;/script&gt;\n&lt;/div&gt;")
</pre>

<p>which result in the output</p>

<pre class="prettyprint">
&lt;div style="color: blue"&gt;
  &lt;a href="/blue?q=%3cCincinatti%3e"
   onclick="alert('Hello, \x3cCincinatti\x3e!');return false"&gt;
    Hello, &lt;Cincinatti&gt;!
  &lt;/a&gt;
  &lt;script&gt;(function () {  
    var o = {"Color":"blue","World":"\u003cCincinatti\u003e"},
        w = "\x26lt;Cincinatti\x26gt;";
  })();&lt;/script&gt;
&lt;/div&gt;
</pre>

<h2>Static auto-escaping</h2>
<p>If a template system's call-graph is readily statically analyzable, the
<tt>escape</tt> module can be used to propagate context and pick an
escaper for each interpolation of an untrusted value into the template output.
</html>
